第 N 章（待总文档排序） / StoryCam Session
生成链路修复、音频能力接入与导演工作台 UI 体系迭代
本 session 从一次 500 错误和“分镜图一直生成中”开始，逐步推进到 StoryCam 从故事世界、核心分镜到片段生成的一整套产品体验重构。
本 Session 摘要
- 生成链路排障：用户从
/api/storycam-sessions/recent?limit=5的 500、核心分镜图不返回、轮询不停等问题切入，推动定位 StoryCam 生成链路的后端与 provider 状态处理问题。 - 资产持久性修复：用户发现从
core-storyboard回退到story-world后资产图丢失，促使会话状态与资产图就绪状态上移，避免返回页面后视觉资产消失。 - 视频音频能力决策：围绕 Seedance 官方能力调研，决定在 clip generation 业务层加入
generateAudio: true，并把雨声、门铃、脚步、环境音乐、对白等声音提示纳入片段提示词。 - 产品表达重构：story-world 的剧本展示从结构化拆段，调整为更像“完整剧本”的整体呈现；随后通过 imagegen 多轮迭代故事世界、核心分镜、片段生成三个工作台页面。
- 流程合并判断：用户明确认为
clip-review和export不应作为独立板块，而应合并进clip-generation，形成“生成、预览、保存、导出”同页完成的简洁流程。 - 协作方式变化：前半段是工程修复与验证，后半段用户多次强调“不是改代码，使用 imagegen 继续迭代 UI 图”，协作重心转为视觉方案探索。
时间线
用户提供了一段 GET /api/storycam-sessions/recent?limit=5 请求，返回 500 Internal Server Error。请求头中包含 Cookie、JWT 和本地会话信息。
Codex 将问题归入 StoryCam 会话恢复与最近项目接口稳定性排查；敏感请求信息不应进入日志或文档，所有 Cookie、JWT、签名 URL 均需要写成 [REDACTED]。
结果 / 影响：后续排查发现 fallback storyboard frames 缺少 visualContent 可能导致 schema 兼容问题，并补充了 artifact schema 相关修复与测试。
“storycam/core-storyboard，在生成核心分镜和拓展分镜时有问题，现在一直轮询结果，没有图片返回。”
Codex 总结为 provider 状态机问题：前端看到 200 轮询并不代表图已完成，服务端需要正确识别 provider 的失败终态，不能把失败任务当成继续处理中。
结果 / 影响：Inference.sh 图像 provider 对状态 11 / task error 等失败终态做了处理，避免无限轮询；同时增加了相应单元测试。
“用户第一次进这个模块的时候是需要分镜脚本和第一个关键帧的图是同步生成的，但是我看现在有分镜脚本，但是图没有。”
Codex 将其识别为核心分镜首屏体验断裂：脚本文本已生成，但关键帧图没有及时返回，用户会误以为流程完成了一半。
结果 / 影响：后续修复覆盖了 storyboard image service 的本地/私有 reference URL 处理，允许服务端获取受保护素材并转换为 provider 可用的数据输入。
“我退回 storycam/story-world 后，之前生成的资产图都没有了。”
Codex 判断这是前端状态归属问题：资产图生成结果不应只挂在某个页面局部状态里，而应提升到 StoryCam workspace 层，页面切换后仍能恢复。
结果 / 影响：资产图 ready 状态被上移到 StoryCamWorkspace，StoryWorldReview 通过回调同步资产图就绪状态；E2E 增加“返回后图片仍存在”的断言。
“需要调研下 seedance 的官方文档，看看如何能生成带有音频的是视频？”随后补充：“在 clip generation 的业务层加一个 generateAudio: true，并把提示词补上‘雨声/门铃/脚步/环境音乐/对白’等音频描述。”
Codex 基于官方文档调研，将音频能力作为 clip generation 的业务层能力，而不是单纯 UI 文案；提示词需要和分镜脚本、分镜图互相支撑。
结果 / 影响：generationJobService.toVideoProviderInput 增加 generateAudio: true，clipPromptPacketService 增加 Native audio plan，覆盖雨声、门铃、脚步、音乐、对白等声音要素。
“story-world 板块里的剧本渲染，为什么是如图中所示的结构化表达？主要考虑是什么？我觉得这部分应该是一个剧本的整体呈现，会不会更好。好，改下，我看看效果。”
Codex 先解释结构化表达的初衷是方便资产拆解和后续生成，但接受用户判断：面向普通用户的 story-world 更应该像“完整剧本审阅”，而不是专业生产表格。
结果 / 影响：剧本 UI 从“摘要 + 剧情卡片”调整为“故事一句话 + 完整剧本 + 关键片段”，既保持可生成信息，又降低工业化表格感。
用户围绕登录后首页输入框反复给出竞品参考：“把这些方向放到输入框下面”，“把拍法倾向放到输入框里左下一排”，“最近项目横向宽度应该和输入框一致”，“发现更多应该比上面两个区域都要宽一些”。
Codex 使用 imagegen 进行多轮 UI 概念迭代，重点围绕输入框比例、拍法倾向入口、创作方向 chips、最近项目和发现更多的宽度层级关系。
结果 / 影响：这一段建立了后续所有工作台页面的视觉基准：黑色电影感、霓虹青/粉点缀、居中工作区、少解释、多操作、避免营销落地页感。
多次明确：“不是改代码，而是使用 $imagegen 再迭代一版 UI 图。”
Codex 停止继续实现代码，把工作方式切换为“视觉方案生成器”：只打开页面观察和用 imagegen 生成 UI mockup，不再改动业务代码。
结果 / 影响：协作边界被澄清。此前已有一些 UI 代码改动和 PR 草稿存在，但此后用户意图是继续探索图，不是落地实现。
“综合考虑图 1 首页的 UI 视觉，使用 imagegen 给 /storycam/story-world 板块设计迭代新的 UI 图……视觉和整体排版有不少提升空间。”随后补充：“最下方的资产细节板块可以去掉；‘对，生成核心分镜’这组按钮是悬浮在屏幕最下方的。”
Codex 观察本地 story-world 后，将其从“后台审核页”改想为“私人导演工作台”：顶部横向流程、剧本主锚点、右侧资产卡片、底部固定确认按钮。
结果 / 影响：story-world 的目标形态明确为：确认故事世界，不是生产后台；底部行动条固定悬浮，滚动不影响核心下一步操作。
“给 /storycam/core-storyboard 板块设计迭代新的 UI 图。”随后提出约束：“每个分镜图上不用放分镜脚本文本；02 到 09 要顺时针顺序；分镜脚本有一个布局展示就行；拓展分镜图 8/8 这个布局可以不要。”
Codex 将核心分镜页从“单张主卡 + 大空白”改想为“9 帧导演画布”：中心主帧，周围八张扩展分镜顺时针排列，脚本集中在一个可折叠/可滚动的侧栏。
结果 / 影响：交互模型变为“点击中心主帧后，其他 8 个自动延展”。UI 可以展示一部分分镜正在生成、一部分可点开放大；不再需要“打开拓展画布”和“当前选中”模块。
“我觉得 clip-review 和 export 两个板块应该是合并到 clip-generation 里的，不应该单独存在。”
Codex 观察当前 export 页面后，提炼为产品流程问题：如果生成、审核、导出拆成多个顶层步骤，普通用户会感觉一直跳转；更适合在一个片段工作台中完成。
结果 / 影响：片段生成页被重新定义为综合工作台：视频预览、音频提示、重生、保存、导出都在同页完成。
用户继续压缩方案：“进度条挪到导航条中间区域”，“不应该有截图这个 tab 条”，“没有‘生成状态 / 预览确认 / 账号内作品’这几个小板块”，“生成提示词不展现”，“整体要简洁，交互顺畅清晰”。最后补充：“顶部导航中间的三步主流程 icon 太不协调……不要右侧‘雨夜便利店·无声告白’这个板块。”
Codex 将片段生成页进一步极简化：三步主流程放入导航栏中间，使用低调小圆点和细线；主体改为单列视频播放器工作台，移除右侧信息面板和内部 tab。
结果 / 影响：clip-generation 的设计方向最终收敛为“单屏播放器工作台”：主视频预览、紧凑时间线、底部固定导出按钮，减少状态卡和解释文本。
关键时刻
1. 从 200 轮询到失败终态识别
问题：网络面板显示轮询请求 200，但没有图片返回。
为什么重要：用户看到“生成中”会等待，系统如果不识别 provider 失败终态，就会形成无尽等待。
处理：图像 provider 增加失败状态判断，并在服务端将失败任务转为可解释错误，而不是继续轮询。
2. 资产状态应属于工作区，而不是页面
问题：回退到 story-world 后资产图消失。
为什么重要：StoryCam 的流程是多页面连续工作，如果每个页面独立持有生成状态，用户会感觉资产丢失。
处理：资产图 ready 状态被提升到工作区层，页面恢复时仍能看到之前生成的结果。
3. 音频不是装饰，而是片段生成输入
问题：如何让 Seedance 生成带有声音的视频。
为什么重要：StoryCam 的目标是私人故事短片，雨声、门铃、脚步和对白会直接影响情绪表达。
处理：业务层加入 generateAudio: true，并把声音要素写入提示词结构，而不是只在 UI 上描述。
4. 从生产表格转向用户可读剧本
问题：story-world 的剧本展示过于结构化，像内部生产数据。
为什么重要：普通用户需要确认“这是我的故事”，而不是阅读专业镜头表。
处理：改成故事一句话、完整剧本和关键片段组合，保留生成所需结构，同时强化整体叙事感。
5. 片段生成、审核、导出合并成一个工作台
问题：clip-review 和 export 作为独立步骤让流程显得割裂。
为什么重要：片段生成是用户最后看到成果的核心时刻，跳转太多会打断确认和导出的连续感。
处理：将它们合并进 clip-generation：同页播放、同页重生、同页保存、同页导出。
工程证据
代码与测试线索
- API 修复：
src/features/storycam/domain/artifactSchemas.ts处理 fallback storyboard frame 的visualContent缺失兼容。 - Provider 修复：
src/lib/providers/inferenceSh/imageProvider.ts识别失败终态，避免无限轮询。 - 图片引用处理：
src/server/storycam/storyboardImageService.ts支持服务端获取本地/私有素材引用并交给 provider。 - 资产恢复：
StoryCamWorkspace与StoryWorldReview之间同步资产图就绪状态。 - 音频生成：
generationJobService与clipPromptPacketService增加generateAudio: true和原生音频提示计划。
验证与 PR 状态
- 本地验证：session 摘要记录了
pnpm typecheck、pnpm test、API 测试与目标 E2E 测试通过。 - PR：浏览器中可见 Draft PR
#2：[codex] Upgrade StoryCam story world UI。 - Branch：
codex/story-world-ui-upgrade，合并目标dev。 - Commit：
d51f316，标题为 Upgrade StoryCam story world UI。 - CI：PR 页面显示 lint/typecheck/test/build 检查成功；Playwright E2E 当时仍在运行，最终结果未在本 session 中确认。
说明：用户后续明确要求“不是改代码，而是使用 imagegen 继续迭代 UI 图”，因此后半段主要产出为 UI 概念图与产品决策，而不是新的代码提交。所有 Cookie、JWT、签名 URL、私有素材链接与 provider 原始 payload 已脱敏为 [REDACTED]。
对外讲解用总结
这一段 StoryCam 的开发，从“为什么图片一直不回来”这样一个具体故障开始，逐步串起了生成式产品最关键的几件事：后端要正确处理 provider 的失败状态，前端要能在跨页面流程中保留资产结果，视频生成不只是画面，还要把声音作为提示词与业务参数的一部分。完成这些基础修复之后，团队把注意力转向产品体验本身：StoryCam 不是专业短剧生产后台，而是普通用户的私人故事剧场。因此 story-world 要像确认完整故事，core-storyboard 要像一个 9 帧导演画布，clip-generation 则要把生成、预览、保存和导出合并成一个顺畅的片段工作台。这次 session 连接了前面的基础能力修复，也为后续真正落地统一 UI 和收敛流程打下了产品方向。